feat(nucleus): Expose dataset_item_id on exported items, annotations and predictions - #473

Batch exports only ever returned reference_id on the exported item, so keying an exported prediction back to a Nucleus dataset item meant a second lookup.

This is an inconsistency fix, not a new field: the single-item endpoints (/dataset/:id/loc, /refloc, /iloc) already return dataset_item_id, and the public API docs (ApiDocsPage/slices/batch-export.md) already document it in the batch-export response. The batch export was the odd one out.

Pairs with scaleapi PR: luke/nucleus-export-dataset-item-id.

What changed

dataset_item_id now appears everywhere reference_id already does:

• DatasetItem gains the field, wired through from_json — the single deserialization entry point, so every SDK path that returns an item picks it up, not just exports.
• Every Annotation / Prediction subclass gains it (box, line, polygon, keypoints, cuboid, category, multicategory, segmentation). convert_export_payload stamps it down from the item exactly as it already does for reference_id.
• The scene/video export docstring documents it on each track frame.

Read-only semantics

The field is server-assigned, and mirrors how DatasetItem.phash was done:

The __eq__ exclusion matters: without it, every existing test that compares a locally-built annotation against its round-tripped twin would start failing.

Exports from a backend that doesn't return the field leave it None rather than throwing, so this SDK version is safe against an un-upgraded backend.

Verification

The test suite requires live API keys (conftest.py hard-asserts on NUCLEUS_PYTEST_API_KEY), so it could not be run locally. Verified offline instead by driving convert_export_payload directly:

• every geometry type on both the annotation and prediction paths carries the id
• a local object still compares equal to its round-tripped self
• to_payload output is unchanged
• an item payload with no dataset_item_id yields None everywhere and does not raise

Formatted with the repo-pinned black 23.12.1 (a newer local black introduced unrelated reformatting, which was reverted).

🤖 Generated with Claude Code

Greptile Summary

The PR exposes the backend-assigned dataset_item_id on dataset items and all supported annotation and prediction objects while preserving upload payloads and existing equality behavior.

• Adds optional, read-only dataset_item_id fields and deserialization across item, annotation, and prediction models.
• Propagates each exported item's identifier to its converted annotations and predictions.
• Documents scene-frame identifiers and releases the change as version 0.20.1.

_{Reviews (1): Last reviewed commit: "feat: expose dataset_item_id on exported..." | Re-trigger Greptile}